Klasör yapısını, adlandırmayı ve yazılı korunması gereken kuralları standardize ederek yapay zeka tarafından üretilen kodu incelenebilir hale getirin; böylece bir ekip güvenle devralıp değişiklikleri yayına alabilir.
Yapay zeka prototipleri genellikle tek bir sebepten başarılı olur: sizi hızlıca “çalışır” hale getirirler. Sorun, “çalışır” durumunun bir ekip tarafından “bakımı yapılabilir” hale gelmesi gerektiğinde başlar. Bir prototip kısa yolları tolere edebilir çünkü aynı kişi (veya aynı sohbet) tüm bağlamı taşır. Bir ekip bunu yapamaz.
Yapay zeka tarafından üretilen kod, niyet her zaman görünür olmadığından insan yazımı koda göre daha zor inceleniyormuş gibi hissedilebilir. İnsan kodu genellikle iz bırakır: tutarlı kalıplar, tekrarlanan seçimler ve neden bir şeyin var olduğunu açıklayan birkaç yorum. AI çıktısı doğru olabilir, ama yine de stilleri karıştırabilir, dosyalar arasında kalıpları değiştirebilir ve varsayımları inceleyenlerin beklemediği yerlere saklayabilir.
Hedef öngörülebilirliktir: öngörülebilir yerler, öngörülebilir isimler, öngörülebilir davranış. Bir ekip üyesi bir şeyin nerede olduğunu, ne adla çağrıldığını ve nasıl davrandığını tahmin edebildiğinde, inceleme bir dedektiflik hikâyesi yerine hızlı bir kontrol haline gelir.
Prototip bir ekip projesine dönüştüğünde tipik olarak ne yanlış gider:
userId vs userid vs user_id), arama güvenilmez olur ve hatalar daha kolay gözden kaçar.Küçük tutarsızlıklar bakım süresini çoğaltır çünkü tekrar eden kararlar almak zorunda bırakır. Her yeni ekran biraz farklı bir klasör konumu, bileşen adı ve veri alma stili içeriyorsa, inceleyenler istikrarlı bir zihinsel model oluşturamaz. Her seferinde kodu yeniden öğrenmek zorunda kalırlar.
Gerçekçi bir örnek: teknik olmayan bir kurucu, basit bir CRM oluşturmak için bir vibe-coding aracı kullanır. Demo iyi gider, ama küçük bir ekip devraldığında üç farklı kimlik doğrulama durumu saklama yöntemi, React bileşenleri için iki farklı isimlendirme stili ve iş kuralları UI kodu ile backend handlerları arasında dağılmış şekilde bulurlar. Hiçbir şey “bozuk” değildir, ama her değişiklik riskli hissedilir çünkü kimse hangi kalıpların gerçek olduğu konusunda emin değildir.
Devretme, seçimleri azalttığınızda kolaylaşır. Kod tabanı sessizce onlara ne yapmaları gerektiğini sürekli söylerse ekipler daha hızlı hareket eder.
"İncelenebilir" demek, yeni bir geliştiricinin repoyu açıp doğru yeri bulması, değişikliği yapması ve başka hiçbir şeyin bozulmadığını teyit etmesi demektir. Bu temel bir beklenti ve birçok AI prototipinin kaçırdığı şey budur.
AI tarafından üretilen kodu incelenebilir yapmak için, zekâya özgü şıklığı bir kenara bırakıp bir insanın güvenle dokunabilmesini düşünün. İncelenebilirlik değişiklik riskini azaltmaktır.
Bir ekip arkadaşı bir pull request incelerken birkaç soruyu hızlıca cevaplamaya çalışır:
Küçük diffler yardımcı olur, ama “küçük” sadece satır sayısı demek değildir. Aynı zamanda stabil sınırlar anlamına gelir: bir alandaki değişiklik alakasız dosyaları değiştirmemelidir.
Mükemmellik gerekmez. Konvansiyonlar, biraz dokümantasyon, birkaç test ve gelecekteki sürüklenmeyi önleyen guardrail’lar gerekir.
Bir inceleyen şu noktaları hızlıca gördüğünde daha güvende hisseder:
Örnek: React frontend ve Go API kurdunuz. Prototip çalışıyor ama “müşteri oluşturma” akışı UI kodu, API handlerları ve veritabanı çağrıları arasında hafifçe farklı alan adlarıyla yayılmış. İncelenebilir kılmak, bu isimleri hizalamak, API sınırını net tutmak ve kuralları (örneğin “email benzersiz olmalı” ve “status sadece active veya paused olabilir”) yazıya dökmektir.
Her şeyi bir ders kitabı projesi gibi yeniden yazmayı hedeflemeyin. Handoff-ready kod, net, tutarlı ve değiştirilmeye güvenle açık olmalıdır; en güzel hali olmasa bile.
Ekip kusurlu koda göz yumabilir. Asıl zor olan, bir şeyin nerede olduğunu bilmemektir. AI tarafından oluşturulan kodun incelenebilir olmasını istiyorsanız, projeyi taraması kolay yapın: üst seviye az sayıda klasör, tutarlı isimler ve konfigürasyon için tek bir bariz yer.
Uygulama büyürken üst seviye haritasını sabit tutun. Pek çok devretme, her deneme için yeni klasörler ortaya çıktığı için başarısız olur. Bunun yerine üç kaygıyı ayırın: uygulama bileşimi (ekranlar, route’lar), çekirdek iş kuralları ve altyapı.
Uyarlayabileceğiniz pratik bir desen (web uygulama örneği):
/
/app # routes/pages and UI composition
/core # domain logic: entities, rules, use-cases
/ui # reusable components, styles, design tokens
/infra # db, api clients, queues, auth adapters
/config # env schema, feature flags, app settings
/scripts # local tooling, seed data, one-off tasks
/docs # handoff notes, invariants, decisions
İlk versiyonunuz hızlı üretildiyse, bu ayrımı görünür tutun. Yeniden üretilebilecek modülleri /generated gibi bir altına koyun ve insan tarafından düzenlenen modülleri /core veya /app altında tutun. Amaç, daha sonra yeniden üretebileceğiniz koda kazara düzenleme yapmayı önlemektir.
Devretmeden önce, bir ekip arkadaşıyla (veya gelecekteki kendinizle) hızlı bir gezinme testi yapın. Giriş UI’sının nerede olduğunu, yetkilendirme kurallarının nerede olduğunu, veritabanı erişiminin nerede tanımlandığını, API base URL’lerinin ve feature flag’lerin nerede ayarlandığını ve “özel” scriptlerin nerede olduğunu sorun.
Eğer herhangi bir cevap “duruma bağlı” veya “bulmak için ara” ile başlıyorsa, her konunun tek, sıkıcı bir evi olana kadar yapıyı ayarlayın. O sıkıcı his, bakımın hızlı ve güvenli olmasını sağlar.
Bir adlandırma kuralı bir söz verir: bir inceleyici adı görür görmez onun ne olduğunu, nerede yaşayacağını ve nasıl kullanılacağını tahmin edebilmelidir.
Dosya adlarından başlayın ve repoda tek bir stil kullanın. Basit bir varsayılan: klasörler kebab-case, React bileşenleri PascalCase, bileşen olmayan TypeScript dosyaları camelCase. Ekosistem beklentisi varsa (ör. Flutter standartleri veya README gibi standart dosyalar) kuralı kırın.
İsimler niyeti göstermeli, uygulamayı değil:
BillingSummaryCard.tsx (neyi temsil ettiği)StripeCard.tsx (satıcı seçimini gömer)RenderBilling.tsx (nasıl yapıldığını, niyeti değil)Bulanık bölmelere karşı katı olun. utils, helpers veya common gibi isimler özellikle kod üretilirken hızla hurda çekmecesine dönüşür. Paylaşılan koda ihtiyacınız varsa kapsam ve amaçla adlandırın, örn. auth/tokenStorage.ts veya billing/billingCalculations.ts.
Özellik klasörleri kullanıcı problemlerini tanımlar. Teknik klasörler kesişen altyapıyı tanımlar. Karıştırmak sınırları gizler.
Pratik bir ayrım: billing, onboarding, inventory gibi özellikler ve api, db, routing, design-system gibi teknik alanlar. Birden fazla istemciniz (web, server, mobil) olduğunda, katmanlar arasında aynı özellik isimlerini tutmak değişiklikleri izlemeyi kolaylaştırır.
Kod incelemelerinde bu kısa rubriği kullanın:
Erken yeniden adlandırın. Devretme sırasında yeniden adlandırmalar ucuzdur; ekip üzerine inşa ettikten sonra pahalı olur.
Invariant, uygulamanızın doğru kalması için değişse bile geçerli kalması gereken kuraldır. AI üretimli kod genellikle “çalışır” çünkü üretici bir dizi kural varsaymıştır, ama bu kurallar sadece istemlerde veya birinin kafasında kalmış olabilir. Onları yazın ki inceleyenler nelerin sessizce değişmemesi gerektiğini bilsin.
İyi invariantler sıkıcı, spesifik ve test edilebilir olur. “Girdileri doğrulayın” gibi belirsiz ifadelerden kaçının. Tam olarak neye izin verildiğini, kimlerin ne yapabileceğini ve kural bozulduğunda ne olacağını yazın.
Handoff acısı çoğunlukla aynı alanlardan gelir:
Bir cümleyi birim testi veya API testi haline getirebiliyorsanız, doğru seviyededir.
Invariantleri insanlar inceleme sırasında doğal olarak baktıkları yerlere koyun:
Uzun belgelerin içine invariantleri saklamaktan kaçının. Eğer normal PR incelemesi sırasında görünmüyorsa, gözden kaçacaktır.
Her invariantı kapsam, kural ve uygulanma noktası ile ifade edin. Örnek: “/api/projects/:id altındaki tüm endpointler için, isteği yapan kişinin proje üyesi olması gerekir; auth middleware’ında uygulanır ve task güncellemelerinde tekrar kontrol edilir.”
Bir invariant değiştiğinde, bunu açıkça belirtin. Dokümanı güncelleyin, değişen kod lokasyonlarına işaret edin ve eski kurala göre başarısız olacak bir test ekleyin veya güncelleyin. Aksi halde ekip genellikle yarı eski yarı yeni davranışı sürdürür.
Eğer bir vibe-coding platformu kullanıyorsanız (ör. Koder.ai), handoff için işe yarayan adımlardan biri ondan oluştururken hangi invariantleri varsaydığını listelemesini istemektir. Sonra bunu takımın gözden geçirebileceği test edilebilir kurallara dönüştürün.
Bir handoff, “makinemde çalışıyor” ile aynı şey değildir. Amaç projeyi okumayı kolay, değiştirilmeye güvenli ve biri yeni açtığında öngörülebilir yapmaktır.
Önce kapsamı dondurun. Bir tarih seçin ve sabit olması gereken kısa bir liste belirleyin (çekirdek ekranlar, ana akışlar, entegrasyonlar). Ayrıca açıkça kapsam dışı olanları yazın ki temizlemeye çalışırken kimse sürekli yeni özellik eklemesin.
Sonra temizlemeyi yeni bir şey eklemeden önce yapın. İncelenebilirlik burada başlar: kod tabanı bir ürün gibi davranmaya başlar, demo gibi değil.
Pratik bir sıra:
Smoke test planını küçük ama gerçek tutun. React uygulama + Go API + Postgres için bu şunlar olabilir: oturum aç, bir kayıt oluştur, yenile, kalıcı olduğunu doğrula ve kısıtlı bir işlemin başarısız olduğunu doğrula.
Okunabilirliğe odaklanan bir inceleme turu yapın, özelliklere değil. Bir ekip arkadaşından 30 dakika ayırıp şunları yanıtlamasını isteyin: “Şeyleri bulabilir miyim?” “İsimler davranışla eşleşiyor mu?” “Invariantler bariz mi?” Onları yavaşlatanları düzeltin, sonra durun.
Handoff öncesi “taze göz” testi yapın. Prototipi inşa etmeyen birinden repoyu açıp size ne yaptığını seslendirmesini isteyin. Başlangıç noktalarını hızlı bulamıyorsa, ekip her değişiklikte bu maliyeti öder.
Basit bir kural: yeni bir geliştirici ana giriş noktalarını iki dakikadan azda bulabilmeli. Bu genellikle README’de uygulamanın nereden başladığını, API giriş noktasını ve konfigürasyonu adlandıran kısa bir rehber ve bu dosyaların gömülmemiş olması anlamına gelir.
Ayrıca inceleme boyutunu kontrol edin. Ana modüller sonsuz kaydırma gerektiriyorsa, inceleyenler problem yakalamayı bırakır. Uzun dosyaları bölün; her dosyanın tek bir işi olsun ve tek oturuşta anlaşılabilsin.
Kısa bir handoff kontrol listesi:
validateUser doğrular, veritabanına yazmaz.Maya teknik olmayan bir kurucudur. Ürünü chat’te tarif ederek bir MVP oluşturur: küçük bir hizmet işletmesi için basit bir CRM. Çalışır: giriş, müşteriler, fırsatlar, notlar ve basit bir admin ekranı. Birkaç hafta sonra iki geliştirici kiralar ve hedef “makinede çalışıyor” durumundan işletmenin güvenebileceği bir hale getirmektir.
Birinci gün, yeniden yazmayla başlamazlar. İncelenebilir yapmaya başlarlar. İlk hamleleri uygulamayı iki kovaya ayırmaktır: çekirdek modüller (her özelliğin bağımlı olduğu şeyler) ve özellikler (kullanıcının dokunduğu ekranlar ve iş akışları). Bu onlara kararları koyacak bir yer ve değişikliği koyacak bir yer verir.
Basit bir özellik haritasında anlaşırlar: çekirdek (auth, veritabanı erişimi, izinler, logging, UI bileşenleri) ve özellikler (customers, deals, notes, admin).
Sonra klasörleri bu haritaya göre ayarlarlar. Önceden dosyalar dağınıktı ve CustomerPage.tsx, customer_view.tsx, custPageNew.tsx gibi karışık isimlendirmeler vardı. Sonrasında her özellik için tek bir ev ve çekirdek kod için ayrı bir alan olur. İncelemeler hızlanır çünkü PR’lar genellikle tek bir özellik klasörü içinde kalır ve çekirdek değişiklikleri bariz olur.
Küçük bir adlandırma kuralı çoğu işi yapar: “klasörler isimdir, bileşenler PascalCase, fonksiyonlar fiil, kısaltma yok.” Böylece custPageNew.tsx CustomerDetailsPage.tsx olur ve doStuff() saveCustomerNote() gibi açıklayıcı hale dönüşür.
Onlar çekirdek dizinin içine kısa bir INVARIANTS.md koyarlar ve bir ana kural yazarlar.
CRM için örnek invariant:
Only the deal owner or an admin can edit a deal. Everyone else can view it, but can’t change status, value, or notes.
Bu cümle backend kontrollerini, veritabanı sorgularını ve frontend UI durumlarını yönlendirir. Sonradan biri “toplu düzenleme” eklediğinde, inceleyenler neyin bozulmaması gerektiğini bilir.
Bir hafta sonra kod kusursuz değildir ama devretme gerçektir:
AI size hızlıca çalışan bir prototip kazandırabilir. Sorun şu ki “çalışıyor” durumu gizli varsayımlara dayanır. Bir ekip daha sonra dokunduğunda, küçük değişiklikler beklenmedik yerlerde işleri bozar.
Yaygın hatalardan biri her şeyi aynı anda refactor etmektir. Büyük temizlemeler tatmin edici gelebilir ama ne değiştiğini ve nedenini görmek zorlaşır. Önce sınırları belirleyin: hangi modüller stabildir, nerede yeni koda izin var ve hangi davranışların değişmemesi gerekir. Sonra alan alan iyileştirin.
Bir diğer sıklık problemi ise aynı kavramın farklı isimlerle çoğaltılmasıdır. AI aynı işi yapan UserService ve AccountManager ya da plan vs pricingTier gibi iki farklı ad yaratmaya heveslidir. Her temel kavram için bir terim seçin ve UI, API ile veritabanı arasında tutarlı şekilde yeniden adlandırın.
Gizli kurallar da kırılganlığın büyük bir kaynağıdır. Gerçek iş mantığı istemlerde veya sohbet geçmişinde yaşıyorsa, repo bakım için zorlaşır. Kuralları kod tabanına açık yorumlar, testler veya kısa invariant belgeleri olarak koyun.
shared, common veya utils gibi kapsayıcı klasörler sessizce hurda çekmecesine dönüşür. Paylaşılan modüllere ihtiyacınız varsa sahip oldukları girdiler, çıktılar ve sorumlulukları tanımlayın ve onları dar tutun.
İş kurallarını UI koduna karıştırmak başka bir tuzaktır. Bir React bileşenindeki hızlı bir koşul bir fiyatlandırma kuralının tek yeri haline gelir. Sonrasında mobil uygulama veya backend uyumsuz olur. İş kurallarını tek bir katmanda tutun (çoğunlukla backend veya domain modülü) ve UI bunun yerine ona çağrı yapsın.
Son olarak, kırılgan kod genellikle inceleme normlarının atlanmasından gelir. Ekipler küçük diffler, net commitler ve açık niyet ister. Bir jeneratör değişikliği üretse bile, bunu normal bir PR gibi ele alın: kapsamı dar tutun, ne değiştiğini açıklayın ve doğrulamayı kolaylaştırın.
Handoff’ı bitiş çizgisi değil, bakımın başlangıcı olarak görün. Amaç basit: yeni bir kişi küçük bir değişiklik yapabilsin ve gizli kuralları bozmadan bunu doğrulayabilsin.
Ekip tercihlerini birkaç yazılı varsayılan haline getirin: herkesin takip ettiği bir klasör haritası, bir adlandırma stili ve invariantler için bir şablon. Bu kurallar baştan kararlaştırıldığında, inceleme yorumları kişisel zevk olmaktan çıkar ve tutarlı kontroller haline gelir.
“Kendine has handoff README” tutun; önemli yerleri işaretlesin: invariantlerin nerede olduğu, uygulamanın nasıl çalıştırılacağı, bir özellik güvenli şekilde nasıl eklenir ve tartışmadan ne değiştirilmemeli. Yeni bir ekip üyesi beş dakikadan kısa sürede cevapları bulabilmeli.
Eğer iş akışınız geri alınabilirliği destekliyorsa, bunu kullanın. Örneğin, Koder.ai anlık görüntüler ve geri alma destekliyorsa, refactorlar veya bağımlılık yükseltmeleri öncesi basit bir güvenlik ağı olabilir. Sahipliği devretmeye hazır olduğunuzda, koder.ai’den kaynak kodu ihraç etmek ekibe normal Git tabanlı çalışma için temiz bir başlangıç sağlar.
Kodun daha tahmin edilebilir hale gelmesiyle başlayın. Klasör yapısını, adlandırmayı ve sınırları hizalayarak bir ekip üyenin dosyaların nerede olduğunu ve nasıl davrandığını depo genelinde aramak zorunda kalmadan tahmin edebilmesini sağlayın.
Yinelenen işlerde (auth state, veri alma, doğrulama, hata yönetimi) her iş için tek bir desen seçin ve bunu her yerde uygulayın. Amaç “en iyi” değil, “tutarlı” olmaktır; böylece inceleyenler uygulamayı her değişiklikte yeniden öğrenmek zorunda kalmaz.
İncelenebilir bir kod tabanı, yeni bir geliştiricinin doğru yeri bulup küçük bir değişiklik yapmasına ve güvenle doğrulamasına izin verir. Değişiklikler sık sık alakasız dosyalara yayılıyor veya kurallar konusunda tahmin yürütme gerekiyorsa henüz incelenebilir değildir.
Küçük ve sabit bir üst seviye klasör seti kullanın ve her sorunu tek bir bariz yere koyun. Uygulama bileşimi (routes/screens), çekirdek iş kuralları ve altyapıyı ayrı tutun; böylece gezinme saniyeler alır, dedektiflik değil.
Yeniden oluşturabileceğiniz kodu /generated gibi net bir klasöre koyun ve insan tarafından düzenlenen kodu /core veya /app gibi kararlı alanlarda tutun. Bu, kazara üzerine yazılan düzenlemeleri ve inceleme sırasında karışıklığı önler.
Bir konvansiyon seçin ve depoda her yerde uygulayın: klasör ve dosya için tutarlı yazım, bileşen adlandırması ve UI, API ile veritabanı arasında tutarlı alan adları. Tutarlılık aramayı güvenilir kılar ve eşleşmeyen isimlerden kaynaklanan ince hatalıları azaltır.
Invariantler, ürün değişirken doğru kalması gereken kurallardır: izinler, benzersiz kısıtlar, izin verilen durum geçişleri gibi. Bunları yazıya dökmek, gizli varsayımları görünür kontrol noktalarına dönüştürür ve inceleyenlerin korumasını sağlar.
İnsanların gerçekten göreceği yerlere koyun: README içinde kısa bir “Sistem kuralları” bölümü ve kuralı uygulayan kodun yanında kısa notlar. Eğer kural normal PR incelemesinde görünmüyorsa, unutulacaktır.
Önce kapsamı dondurun: çalışması gereken küçük bir çekirdek kullanıcı yolculukları listesi ve açıkça dışında bırakılanlar. Sonra klasörleri ve isimleri normalleştirin, ölü kodu silin, minimal bir duman testi kontrol listesi oluşturun ve yalnızca okunabilirliğe odaklanan bir inceleme turu yapın.
Her şeyi baştan yeniden düzenlemekten kaçının, utils gibi yakalanmış klasörlerin oluşmasına izin vermeyin ve iş kurallarını UI koşullarına gömmeyin. Ayrıca farklı isimlerle çoğaltılmış kavramlara dikkat edin ve doğrulama/hata işleme mantığının ekranlar ve endpointler arasında sürüklenmesini önleyin.