Claude Code ile Tutarlı Tasarımlar Nasıl İnşa Edilir? Kod Ajantlarının Tutarsız Tasarım Yapma Sorunu ve Çözümü.

Kod ajantları (coding agents) kullanan yazılım geliştiricilerin büyük bir kısmıyla karşılaştığı tutarsız tasarım sorunu, Claude Code veya Codex gibi araçların önceki tasarımı takip etmeyip kendi standartlarını uygulama eğiliminden kaynaklanıyor. Uygulamada farklı font boyutlarının kullanılması, farklı yerlerde değişen düğmenler ve renk, boyut ya da stilde tutarsız açılır menüler (dropdown) ile hover modülleri gibi kullanıcı arayüzü ögelerinin ortaya çıkması bu sorunun somut belirtileri olarak öne çıkıyor. Bu durumun temel nedeni, kod tabanında merkezi bir yapılandırma eksikliği olduğundan ajantların yeni özellik eklerken kendi desenlerini oluşturmaya başlamasıdır.

Bu tutarsızlıkların önemi göz ardı edilemeyecek düzeydedir; çünkü uygulama içinde farklı görünen arayüz öğeleri uygulamanıza profesyonel olmayan ve eksik bir ilk izlenim veriyor. Tasarım konusunda fazla zaman ayırmayı tercih etmeyen mühendisler için bile bu konu kritik nitelik taşır, çünkü makale boyunca paylaşılacak tekniklerle kod ajantları otomatik olarak daha tutarlı çalışacak ve siz de tüm ajantların oluşturduğu tasarımları takip etmek için harcadığınız zamanı azaltacaksınız. Bu sayede arayüz üzerinde ayırdığınız emek azalacak; kod ajantları ilk denemede doğru sonucu verme olasılığı artacak.

Kod Ajantları Neden Tutarsız Tasarımlar Oluşturuyor?

Sorunun kökenini anlamak için önce bu durumun neden ortaya çıktığını irdelemek gerekir. Kod ajantlarının farklı tasarımlar üretmesi ve uygulamanızdaki standartları takip etmemesi, büyük ölçüde arayüzü nasıl yapılandırdığınızla ilişkilidir. Eğer kod ajanlarını her şeyi kendileri uygulama konusunda serbest bırakırsanız ve onlara kodu ya da UI ögelerini merkezi olarak nasıl düzenleyeceklerini manuel olarak anlatmazsanız, ajantlar otomatik olarak uygulamanızın farklı bölümlerinde farklı standartları kullanmaya başlar.

Bunun sebebi şudur: Bir kod ajanına yeni bir özellik implemente etmesi istendiğinde, uygulamada önceden belirlenmiş bir standardı görmeyince kendi tasarım desenlerini oluşturmaya yönelir. Örneğin, o sayfada iyi çalıştığını düşündüğü kendi font boyutunu kullanabilir, sayfadaki diğer tasarımlarla uyumlu görünen düğmeler oluşturabilir ve benzeri yaklaşımlara başvurabilir.

Kod ajantları temelde desen tanıyıcılardır. Kod tabanında zaten mevcut olan desenleri takip ederler. Ve kod tabanındaki önceki desenin bir UI yapısı ya da genel tasarım standardı içermemesi durumunda, ajantlar bu deseni sürdürür ve ekledikleri her yeni özellik için kendi tasarım sistemlerini implemente ederler.

Makale Yazarı

Bu bağlamda sorunun çözümü zaten belli görünmektedir: Tüm UI ögelerini tek bir konumda merkezileştirmek. Ancak bu, kolay bir iş değildir; yalnızca mevcut sorunu düzeltmek yeterli değil, aynı zamanda sürekli üzerinde çalışılması gereken bir süreçtir çünkü kod ajantlarının hâlâ zayıf yönleri vardır ve varolan standartları görmezden gelebilir ya da yeni olanları ortaya çıkarabilir. Örneğin, sadece yeni bir sayfada kod implemente ettiğinizde, uygulamanızdaki tasarımın tutarlı kalması için bu öğeleri sürekli olarak uyumlu tutmaya çalışmalısınız.

Tutarlı Tasarımı Nasıl Sağlayabilirsiniz?

Tasarımınızı nasıl tutarlı kılacağınızı konuşmaya başlamadan önce, kod tabanınızdaki tasarım standartları zaten tutarlı ve birleşik değilse bu sorunu nasıl düzelteceğinizi anlatacağım. Ardından ise tasarım standartlarını birleştirmeye devam edeceğim.

Tutarsız Tasarımı Düzeltmek

Zaten oldukça fazla emek verdiğiniz ve uygulamanızdaki tasarım tutarlı olmayan bir kod tabanınız varsa, yapmanız gereken ilk şey yeniden yapılandırmaya (refactor) başlamak. Tüm UI ögelerini tek bir klasörde saklayacak şekilde yeniden yapılandırmalısınız. Yapay zeka ya da kod ajanı yeni bir şey implemente etmek ya da yeni bir UI öğesi kullanmak istediğinde, kendi yeni UI öğesini yazmak yerine UI klasöründen mevcut bir öğeyi seçmek zorunda kalmalıdır. Yani ajantları kendi UI ögelerini oluşturmaktan menmeniz ve her zaman klasördeki onaylanmış öğelerden birini seçmelerini sağlamanız gerekir.

Bazen yeni UI ögeleri implemente etmek isteyebilirsiniz; böyle bir durumda bu ögeleri paylaşılan birleşik klasore ekleyebilir ve ajanta bunun kullanmasını sağlayabilirsiniz. Ancak ajanta, kendi UI ögelerini kodun birleşik klasör dışındaki herhangi bir yerine implemente etmenin yasak olduğunu son derece net biçimde belirtmelisiniz.

Bu amaçla aşağıdaki gibi bir prompt ile başlamanız önerilir:

Bu işlemi başlattığınızda, çalıştırdığınız kod ajanı (Claude Code ya da Codex fark etmeksizin) kod tabanınızı taramaya başlayacak ve düzeltmesi gereken çok sayıda sorunla karşılaşacaksınız. Bu nedenle, önce özellikle düğmeler veya fontlar gibi belirli öğelerle başlamanızı öneririm; bunlar yukarıdaki promptta ayrıca belirtilmiştir. Ardından ajanta, değişikliklerden önce sayfaların nasıl göründüğünü ve değiştirdikten sonra nasıl göründüğünü gösteren ön-ve-son (before-and-after) görselleri içeren bir HTML raporu hazırlamasını istemenizi öneririm; bu rapor screenshots ile desteklenmelidir. Bu sayede raporu kolayca tarayabilir, kaydırarak arayüzün kabul edilebilir olup olmadığını değerlendirebilir ve düzeltilmesi gereken bir şey varsa ajanta geri bildirim verebilirsiniz. Kod ve UI onaylandıktan sonra kod ajanı bunu geliştirme ortamınıza otomatik olarak merge edebilir ve siz bir sonraki öğeye geçebilirsiniz.

Her öğeyi düzelttikden sonra ayrıca tamamen ayrı bir kod ajanı çalıştırmanızı öneririm. Bu ajan sadece hâlâ eksik olan herhangi bir öge olup olmadığını kontrol etmek için görevlendirilmelidir. Örneğin, tüm düğmeleri düzeltip merge ettikten sonra, ayrık bir ajan çalıştırarak artık eksik olan ya da birleşik UI klasörüne eklenmemiş herhangi bir düğme olup olmadığını ve bunların düzeltilmesi gerektiğini kontrol etmelisiniz. Çünkü bazen kod ajanı bu öğeleri ilk çalışmada atlayabilir ve her şeyi dahil ettiğinizden emin olmak için ikincil bir temizleme (clean) incelemesi yapmanız gerekir.

Ardından tüm kod tabanınızı yeniden yapılandırarak bu süreci sürdürmeniz yeterlidir; elbette bu biraz zaman alacaktır. Kod ajantlarıyla bunu oldukça etkili biçimde gerçekleştirebilirsiniz. Kod tabanınıza bağlı olarak, bu işlemi etkili bir şekilde yürütüp kod ajanlarına işlerini yapmalarına izin verirseniz, birkaç gün içinde sorunsuz biçimde tamamlayabileceğinizi düşünüyorum.

Tasarımı Birleşik Olarak Korumak

Tüm tasarımı düzeltip her şeyi tek bir birleşik klasöre merkezileştirdikten sonra, artık tasarımı birleşik olarak koruma zamanı gelmiştir. Bunun için ajantların uygulamanız boyunca kullandığı markdown dosyalarında (örneğin agents.md ve CLAUDE.md gibi) son derece net biçimde belirtmelisiniz ki yeni tasarım implementasyonları asla icat edilmemeli; her zaman merkezi UI klasöründen seçim yapılmalıdır. Adil olmak gerekir ki, bazen bunu kendiniz doğrulamanız gerekir çünkü kod ajantları, ajantların daima bu standardı takip etmesi gerektiğini söyleyen son derece net bir dosyanın ve birleşik UI klasörünüzün mevcut olmasına rağmen yeni bir şeyi implemente etmeye çalışıp varolan standardı takip etmemeye meyilli olabilir. Ajantların bazen kendi tasarımlarını implemente etmeye devam etmek isteme eğilimlerini gözlemliyorum; bu elbette oldukça can sıkıcı bir durum.

Buna rağmen yapabileceğiniz bir şey bulunmaktadır. Geliştirme ortamında her zaman çalıştırdığınız bir kod inceleme ajanı (coding review agent) olduğunuzdan eminim; eğer böyle bir ajantınız yoksa, bunu kesinlikle implemente etmenizi önemle öneririm. Kodunuzu etkili biçimde inceleyip geliştirme ya da üretim ortamına gitmeden önce herhangi bir hata tespit edebilmeniz için AI ile kod incelemesi yapmanız konusunda farklı makaleler zaten yazdım.

Bu ajant için mevcut promptu güncelleyebilir ve ona ayrıca merkezi UI klasöründen gelmeyen tüm UI ögelerini kontrol etmesini ve bunu nispeten ciddi bir sorun olarak işaretlemesini söyleyebilirsiniz. İnceleme ajanları buna genellikle P2 sorunu yani kritik olmayan bir sorun olarak adlandırır. Ancak siz bu durumun daha büyük bir sorun olduğunu vurgulamanız gerektiğini düşünüyorum; çünkü bunun gerçekleşmesine izin vermeye devam ederseniz, uygulamanızda büyük bir soruna dönüşecektir. Bu nedenle ajanta bunu derhal işaretlemesini söyleyin ki kodu geliştirme ya da üretim ortamınıza merge etmeden önce onu yerinde düzeltebilesiniz. Bu, tasarımı birleşik tutmanızı, uygulamanızın temiz ve profesyonel görünmesini sağlamanızı ve kod ajanlarının takip etmeleri gereken tasarım desenlerini takip etmemelerini önlemenizi garantileyecektir.

Sonuç

Bu makalede, Claude Code ya da kullandığınız diğer herhangi bir kod ajanıyla tasarımtı nasıl tutarlı kılacağınızı tartıştım. Bu, kod ajanlarının yeni özellikler implemente ettiklerinde daima kendi tasarımlarını icat etmeye çalışmasından kaynaklanan ve kendim de deneyimlediğim bir sorundur. Uygulamanın doğru şekilde görünmesini sağlamak için çok fazla zaman ayırdığınız için elbette oldukça can sıkıcıdır; üstelik bazen hatalarını tespit etmek zor olabilir. Örneğin, bir font boyutunun çok düşük ya da çok yüksek olması uygulamanıza daha az profesyonel bir izlenim verir ve bu nedenle bunu önlemek istersiniz.

Tüm UI ögelerini merkezi bir klasörde tutarak tasarımı mümkün olduğunca tutarlı kılmanızı sağlayacak şekilde kodunuzu Don’t Repeat Yourself (DRY) yani Tekrarlamayın prensibi çerçevesinde yeniden yapılandırabileceğinizi tartıştım. Ayrıca, bunu yalnızca yeniden yapılandırma ile düzeltmekle kalmayıp, yeni UI kodu gönderirken katı kurallar ve incelemeler ekleyerek tasarımı tutarlı biçimde koruyabileceğinizi de anlattım. Tüm merkezi UI ögeleri takip edildiğinden emin olmak için sürekli olarak yeniden yapılandırma ve bazı kontroller yapmanızı, herhangi bir sorun keşfettiğinizde ise derhal temizlemenizi öneririm. Ajantic kodlama çağında tutarlı yeniden yapılandırma artık zorunluluk haline gelmiştir.